home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 033a / obul_003.zip / OBUL.DOC < prev    next >
Text File  |  1991-04-18  |  20KB  |  603 lines
  1. --------------------------------------------------------------------
  2. Table Of Contents for OBUL
  3.  
  4. 1  Introduction
  5.    1.1  Overview
  6.    1.2  Package Contents
  7.         1.2.1  Manifest
  8.         1.2.2  Validation Information
  9.         1.2.3  Direct From Author
  10.    1.3  OBUL Requirements
  11.    1.4  Formalities
  12.         1.4.1  Registering
  13.         1.4.2  Distributing OBUL
  14.         1.4.3  Fees
  15.                1.4.3.1  Copying And Distribution Fees
  16.                1.4.3.2  To The Author
  17.         1.4.4  Warranty, Liability, And Other Myths
  18. 2  Configuration
  19.    2.1  File Organization
  20.    2.2  OBUL.CTL Description
  21.    2.3  Preparing A Bulletin
  22.    2.4  Examples
  23. 3  Operation
  24.    3.1  Command Line Arguments
  25.         3.1.1  -?, display more help
  26.         3.1.2  -H, (same as -?)
  27.         3.1.3  -C, compile OBUL.CTL into OBUL.PRM
  28.         3.1.4  -G, generate bulletin menu
  29.         3.1.5  -D, decompile OBUL.PRM
  30.         3.1.6  -M, display OBUL menu interface
  31.         3.1.7  drive:\path\
  32.    3.2  Using With Opus
  33. 4  Having Problems?
  34. 5  Revision History
  35. 6  Future Enhancements
  36. 7  Credits
  37.    7.1  Contacting The Author
  38.    7.2  Special Thanks
  39.  
  40.  
  41. --------------------------------------------------------------------
  42.  
  43.  
  44. 1  Introduction
  45.    ------------
  46.  
  47.  
  48. 1.1  Overview
  49.      --------
  50.  
  51. OBUL is the Opus Bulletin Utilization Language.  It
  52. gives Opus CBCS sysops the ability to generate a
  53. bulletin menu which is specific to the current user. 
  54. Important or modified bulletins may be highlighted, manually
  55. or automatically, to direct the user's attention.  A bulletin
  56. is an Opus .BBS file, which in turn can present text, execute
  57. a DOS program, or whatever.
  58.  
  59. Technical Nutshell:  When OBUL is called to generate a bulletin
  60. menu, the LASTUS##.DAT file is read to determine date of last
  61. visit and access level.  This information is used to construct
  62. the bulletin menu which can be displayed to the user at any time.
  63.  
  64. As OBUL is being released, Opus 1.20 is also near release.  OBUL
  65. was designed for Opus 1.14.  If the LASTUS##.DAT file does not
  66. change in Opus 1.20, then OBUL will work with it also.  If there
  67. is a change, be watching for a new release of OBUL.
  68.  
  69.  
  70. 1.2  Package Contents
  71.      ----------------
  72.  
  73.  
  74. 1.2.1  Manifest
  75.        --------
  76.     
  77. The official OBUL package consists of the following files. 
  78. This product may only be distributed in its full,
  79. unadulterated form with all the files listed in the manifest.
  80.  
  81. OBUL.EXE        - main program
  82. OBUL.CTL        - a sample control file
  83. OBUL.DOC        - documentation
  84. OBUL.C          - source code
  85. OBULOECC.BAT    - example batch program to compile OEC files
  86. WELCOME.OEC    - example file that calls OBUL
  87. CPU.OEC        - bulletin of simple text
  88. NEWFILES.OEC    - bulletin which calls a DOS program
  89. REGISTER.OEC    - bulletin which asks and records answers
  90.  
  91.  
  92.  
  93. 1.2.2  Validation Information
  94.        ----------------------
  95.  
  96. VALIDATE 0.3 Copyright 1988-89 by McAfee Associates.  (408) 988-3832
  97.  
  98.           File Name:  obul.exe
  99.                Size:  57,872
  100.                Date:  4-18-1991
  101. File Authentication:
  102.      Check Method 1 - 9FAF
  103.      Check Method 2 - 15C8
  104.  
  105. If you get different results, you may wish to obtain OBUL directly
  106. from the author.  To do this, refer to the Direct From Author section
  107. for instructions.
  108.      
  109.  
  110. 1.2.3  Direct From Author
  111.        ------------------
  112.  
  113. If you question the validity of these files, you may obtain them
  114. directly from the author.  A file request magic word, OBUL, has
  115. been established.  For address information, refer to the section of
  116. this manual about Contacting The Author.
  117.  
  118. If you wish to try, OBUL may be available at HST speeds from
  119. 1:373/2, but no promises.
  120.  
  121.  
  122. 1.3  OBUL Requirements
  123.      -----------------
  124.  
  125. OBUL is dependent upon an Opus embedded command compiler.
  126. Two that I am aware of: OECC and OACOMP.  OBUL generates the
  127. ".OEC" bulletin file only at this time.  This file must be
  128. compiled using an OEC compiler to generate a ".BBS" file.
  129. These OEC compilers are obtainable from most Opus systems,
  130. including my own.  A note about OACOMP.  When you use the
  131. '-g' option to generate a menu, OACOMP will generate warnings
  132. about labels.  This is mentioned in the OACOMP documentation.
  133. The labels are fine, they just use the OECC format.
  134.  
  135. You may use any OEC compiler you choose.  OBUL will call a program
  136. by the name of "OBULOECC" and pass two arguments.  The first is the
  137. full path to .OEC version of the bulletin menu created by OBUL.  The
  138. second is the full path to the .BBS version of the bulletin menu.
  139. Here is what OBUL would do if the PATH in OBUL.CTL was defined as
  140. h:\opus\misc\bullets.
  141.  
  142.    OBULOECC h:\opus\misc\bullets.OEC h:\opus\misc\bullets.bbs
  143.  
  144. OBULOECC can be a .EXE, .COM, or .BAT.  If you need to reorganize the
  145. arguments or not use them both, the .BAT file will be the best option.
  146. A sample OBULOECC.BAT file is included that can use either of the OEC
  147. compilers that were mentionedé above.
  148.  
  149. The source code was compiled with MIX Power C, but other
  150. compilers should handle it without much rework.  To compile,
  151. you will need to acquire OTOOLKIT, a C library of routines
  152. and header files for the Opus 1.1x data structures.  This is
  153. obtainable from most Opus systems.
  154.  
  155. OBUL is for the Opus CBCS of course.
  156.  
  157.  
  158. 1.4  Formalities
  159.      -----------
  160.  
  161. OBUL is free software.  All commercial rights are reserved by
  162. the author.  Modified versions must not be redistributed.
  163.  
  164.  
  165. 1.4.1  Registering
  166.        -----------
  167.  
  168. No registration is required.  However, if you send me information
  169. on how to contact you by email, I will notify you when a new
  170. release is available.
  171.  
  172.  
  173. 1.4.2  Distributing OBUL
  174.        -----------------
  175.  
  176. This product may only be distributed in its full,
  177. unadulterated form with all the files listed in the manifest.
  178. The source code is provided for users to study or modify for 
  179. personal use.  If you make a change others might benefit from,
  180. please notify the author so it can be officailly incorporated.
  181. Do not redistribute modified versions of OBUL.
  182.  
  183.  
  184. 1.4.3  Fees
  185.        ----
  186.  
  187. 1.4.3.1  Copying And Distribution Fees
  188.          -----------------------------
  189.  
  190. OBUL is free software.  However, you may be charged a fee when
  191. you obtain it from a pay bulletin board system or from one of
  192. those PD/Shareware catalogs.  This is allowable, but please note
  193. that these fees are for copying and distribution only.  OBUL may
  194. not be sold as a commercial product, unless permission is granted
  195. by the author.
  196.  
  197.  
  198. 1.4.3.2  To The Author
  199.          -------------
  200.  
  201. I do not ask a fee for your using OBUL.  However, if you have
  202. any educational software that is for IBM and compatible personal
  203. computers, please send it.  I'm trying to form a large repository
  204. of educational software for the benefit of children, their parents
  205. and teachers, and my daughter.  Your additions would be most appreciated.
  206.  
  207.  
  208. 1.4.4  Warranty, Liability, And Other Myths
  209.        ------------------------------------
  210.  
  211. This is free software.  As for warranties or liability, you
  212. get what you pay for.  The software works on my system and I
  213. have confidence in its operation.  I do welcome comments, bug
  214. reports, and suggestions for enhancements.  If you have any
  215. problems, I will do my best to help.  Refer to the section on
  216. Contacting The Author for further information.
  217.  
  218.  
  219. 2  Configuration
  220.    -------------
  221.  
  222. 2.1  File Organization
  223.      -----------------
  224.  
  225. Place OBUL.EXE where it can be executed by Opus.  If it is
  226. not accessible in the PATH of your AUTOEXEC.BAT file, you
  227. will have to give a full pathname when executing OBUL.
  228.  
  229. OBULOECC.BAT should be accessible from your DOS PATH.
  230.  
  231. The OBUL.CTL and OBUL.PRM can be anywhere.  A command line
  232. argument specifies where they are located.  The default is
  233. the current working directory, most likely your Opus system
  234. directory.
  235.  
  236. The bulletins can be anywhere since a full path is specified
  237. for each in the OBUL.CTL file.
  238.  
  239. FYI:  The author placed OBUL.EXE, OBUL.CTL, and OBUL.PRM in his
  240. main Opus directory, H:\OPUS, and the bulletin files were stored
  241. with the Opus .BBS file in the MISC directory, H:\OPUS\MISC.
  242.  
  243.  
  244. 2.2  OBUL.CTL Description
  245.      --------------------
  246.  
  247. Here is a line by line description of the OBUL.CTL file.
  248. This file is compiled into OBUL.PRM to check for errors.
  249. This insures (to a degree) that OBUL -G (generate) will
  250. always use a valid data file, which is important since
  251. generate is done while the user is online.
  252.  
  253. >>  version
  254. The version number of OBUL that uses this
  255. particluar file format.  Different versions of OBUL
  256. may use different file formats as items are added
  257. and removed.
  258.  
  259. >>  lastpath
  260. Full DOS path to the LASTUS##.DAT file.  Replace ##
  261. with the tasknumber being used by Opus.
  262.  
  263. >>  path
  264. Full path for ouput of the bulletin menu file.  This does
  265. not include the file suffix, it is automatically created.
  266. If you do add the suffix, it will be stripped off.
  267.  
  268. >>  bbs
  269. When generating the OBUL user menu, generate a .bbs file
  270. in the directory specified in the path statement.  This
  271. is currently supported using an external compiler via the
  272. OBULOECC.BAT file.  Options are YES and NO.
  273.  
  274. >>  oec
  275. When generating the OBUL user menu, generate a .OEC file
  276. in the directory specified in the path statement.
  277. Options are YES and NO.
  278.  
  279. >>  columns
  280. Number of columns to use for bulletin menu entries.
  281. Select a number between 1 and 4, inclusive, or choose
  282. automatic to have a best fit done at run-time.
  283.  
  284. >>  order
  285. This determines the order that bulletin entries are displayed
  286. on the menu.  DOWN uses a top-to-bottom order per column, and
  287. ACROSS uses a left-to-right order.
  288. The straight order of the bulletins is based upon the order
  289. the entries are entered the control file.
  290.  
  291. Example:  If listed as A,B,C,Q with 2 columns:
  292.               down           across
  293.               A  C           A  B
  294.               B  Q           C  Q
  295.  
  296. >>  title_text
  297. String of text to display at the top of the OBUL menu that describes
  298. what this menu is to the user.
  299.  
  300. >>  title_color
  301. Color of title_text as available with ANSI, choices are:
  302.  
  303.    black       darkgray       
  304.    blue        lightblue      
  305.    green       lightgreen     
  306.    cyan        lightcyan      
  307.    red         lightred       
  308.    magenta     lightmagenta   
  309.    brown       yellow         
  310.    gray        white          
  311.  
  312. >>  prompt_color
  313. Color of prompt that appears on menu requesting the user to
  314. make a selection from the menu.  Same choices as title_color.
  315.  
  316. >>  display_privileged
  317. Choices are YES or NO.
  318. If YES, menu entries that user does not have access to will be
  319. displayed on the menu, but selecting them will cause a message
  320. to appear indicating lack of access privilege.
  321. If NO, menu entries that user does not have access to will not
  322. be displayed on the menu.
  323.  
  324. >>  format
  325. A string made up of L,C,T,H,E, or spaces that indicates the format
  326. of a menu entry.  Any combination of these may be used.
  327. L-lead character
  328. C-choice character
  329. T-tail character
  330. H-highlight character
  331. E-menu entry text
  332.  
  333. >>  lead_character
  334. These are the choices for the lead character ".-_=([{<"
  335.  
  336. >>  lead_color
  337. Color of lead character, same choices as title color.
  338.  
  339. >>  choice_color
  340. Color of choice character, same choices as title color.
  341.  
  342. >>  tail_character
  343. These are the choices for the tail character ".-_=)]}>"
  344.  
  345. >>  tail_color
  346. Color of tail character, same choices as title color.
  347.  
  348. >>  entry_color
  349. Color of entry text, same choices as title color.
  350.  
  351. >>  highlight_character
  352. Character to use to highlight an entry, "!@#$%*-=+:<>"
  353.  
  354. >>  highlight_color
  355. Color of highlight character, same choices as title color.
  356.  
  357. >>  highlight_blink
  358. If yes, make highlight character blink when it is used.
  359.  
  360. The following are repeated for each menu entry:
  361. choice_character, entry_text, access, file, highlight_mode
  362.  
  363. >>  choice_character
  364. This is the character that is used to select this entry 
  365. from the menu.  Valid choices are any alphabetic or numeric
  366. characters.
  367.  
  368. >>  entry_text
  369. Text that will appear for this menu entry as it's description
  370. or definition.  Basically, what this bulletin is.
  371.  
  372. >>  access
  373. This access level or higher is required to view this bulletin.
  374. Choices are Hidden, Sysop, Asstsysop, Clerk, Extra, Favored, Privil, Worthy, Normal, Limited, Disgrace, Twit.
  375. Only the first letter is actually used by OBUL.
  376.  
  377. >>  file
  378. Three choices:
  379.    full path to a .BBS file to display
  380.    *quit, exit menu and proceed with bbs operation
  381.    *hangup, disconnect user immediately
  382.  
  383. >>  highlight_mode
  384. Three choices:
  385. automatic - highlight entry with highlight character if file date is
  386.             more recent than the date the user last logged on.
  387. always - always highlight entry.
  388. never - never highlight entry.
  389.  
  390. >>  # HELP TEXT
  391. Help may contains up to 20 lines at the end of the OBUL.CTL file.
  392. This text will be used when ? is selected in the menu.
  393. The line "# HELP TEXT" must appear in your CTL file.  It is used
  394. by OBUL to determine the end of the bulletin specifications and
  395. the beginning of the help text.
  396.  
  397.  
  398. 2.3  Preparing A Bulletin
  399.      --------------------
  400.  
  401. A bulletin is simply an Opus .BBS file which may contain Opus
  402. embedded commands.  If after reading the bulletin, the user should
  403. be returned to the OBUL bulletin menu, you must add something to
  404. your bulletin file.  In the .OEC bulletin file, add [display<path>
  405. at the end or [onexit]<path> to the very top.  <path> should be the
  406. full path to the bulletin menu you generated with OBUL.  
  407. (e.g.  H:\OPUS\MISC\BULLETS.BBS)  If you used [onexit], Opus 1.1x has
  408. a problem after about 10 of these.  As I understand it, this problem
  409. has been eliminated in Opus 1.20.
  410.  
  411.  
  412. 2.4  Examples
  413.      --------
  414.  
  415. Example files have been provided and are listed in the manifest.
  416. These example files, which the author has used, have been included
  417. for your benefit.  They give an idea as to what can be done with OBUL.
  418.  
  419.  
  420. 3  Operation
  421.    ---------
  422.  
  423. When you execute OBUL with no options, the following text will
  424. appear on the screen.  This text defines what options are valid.
  425. Also listed is the version number and release date.
  426.  
  427.    OBUL - Opus Bulletin Utilization Language
  428.           Version 003 released 20-APR-91
  429.           Copyright 1991 Keith Ford.  All Rights Reserved.
  430.  
  431.    Usage: OBUL [option] [drive:\\path\\]
  432.    Options are:
  433.      -?,-h = display more help
  434.      -c = compile OBUL.CTL into OBUL.PRM
  435.      -g = generate .BBS/.OEC from OBUL.PRM and LASTUS##.DAT
  436.      -d = decompile OBUL.PRM to screen (stdout)
  437.      -m = display OBUL menu interface
  438.    drive:\\path\\ = drive and path where files are located.
  439.                   Default is current directory.
  440.  
  441.  
  442. 3.1  Command Line Arguments
  443.      ----------------------
  444.  
  445. 3.1.1  -?, display more help
  446.        ---------------------
  447. Use this to display more information about the OBUL product.
  448. This same information is automatically made available with the
  449. '=' option in the OBUL bulletin credits menu entry.
  450.  
  451. 3.1.2  -H, (same as -?)
  452.        ----------------
  453.  
  454. 3.1.3  -C, compile OBUL.CTL into OBUL.PRM
  455.        ----------------------------------
  456. Compile the OBUL.CTL file into OBUL.PRM, which is used by OBUL.EXE.
  457. Compiling checks to see that the OBUL.CTL file is correct and notifies
  458. if errors exist.
  459.  
  460. 3.1.4  -G, generate bulletin menu
  461.        --------------------------
  462. Using information in LASTUS##.DAT and OBUL.PRM, generate the specified
  463. bulletin menu for the current user.
  464.  
  465. 3.1.5  -D, decompile OBUL.PRM
  466.        ----------------------
  467. Create OBUL.CTL information from an OBUL.PRM file.  Output will go
  468. to the screen.  If you wish to capture this to a file, use the DOS
  469. command line:   OBUL -D > OBUL_CTL.TXT.  This file can be directly
  470. recompiled with OBUL -C.  You may recognize that this is patterned
  471. after the Salt/Pepper programs.
  472.  
  473. 3.1.6  -M, display OBUL menu interface
  474.        -------------------------------
  475. This feature has yet to be implemented.
  476.  
  477. 3.1.7  drive:\path\
  478.        ------------
  479. This specifies the path where OBUL.EXE can find the OBUL.PRM file
  480. if using '-G' or '-D', or the OBUL.CTL file if using '-C'.  The default
  481. is the current directory.
  482.  
  483.  
  484. 3.2  Using With Opus
  485.      ---------------
  486.  
  487. The most obvious way is to make it available using the Bulletin option
  488. in the Opus Main Menu.
  489.  
  490. OBUL can be used however you wish.  A typical setup used is to have
  491. the WELCOME.BBS, which is shown to all users, generate the bulletin
  492. menu with OBUL and the '-G' option then display it.  Included is an
  493. example on how this can be done.  However, Opus 1.1x has a noted 
  494. problem using [onexit] commands in OEC files before the user has 
  495. reached the Main Menu.  As I understand it, 1.20 has eliminated 
  496. these problems.
  497.  
  498.  
  499. 4  Having Problems?
  500.    ----------------
  501.  
  502. If you are having problems with OBUL, please provide the information
  503. requested on this form and send it to the author.  The form contains
  504. sample information to act as a guide.  Methods of contacting the
  505. author are listed with the example and in another section of this
  506. document.  Email would be the best method to use, or you can upload
  507. this form to the author's bbs.  Only provide information that you
  508. feel affects the way OBUL may run.  (If you're not sure, list it.)
  509.  
  510. -------------------------------------------------------------------
  511. --                                              OBUL Problem Report
  512. --   YOUR NAME:  Keith Ford                     DATE:  d#-mmm-y#
  513. --     ADDRESS:  203 Creek Trail
  514. -- CITY,ST,ZIP:  Madison, AL 35758
  515.  
  516. -- WAYS TO REACH YOU:
  517. Fido email: Keith Ford at 1:373/12, file attaches okay
  518. Usenet email: sysop@umagic.fidonet.org
  519.               ...!uunet!ingr!infonode!umagic!sysop
  520. upload to Micro Magic at 205-830-2362
  521.  
  522. -- HARDWARE:
  523. 4M extended RAM on motherboard, 80386SX-16MHz
  524. -- SOFTWARE:
  525. MSDOS 3.3, Disk Manager 4.0 (TSR), 2Meg SMARTDRV.SYS cache (TSR),
  526. DESQview 2.31, QEMM 5.11, Opus 1.14, X00 1.24 FOSSIL (TSR)
  527.  
  528. -- DESCRIPTION OF PROBLEM:
  529. Please describe the problem you are having and the conditions under
  530. which they occur.  Also list how you are running OBUL when this
  531. problem occurs.
  532.  
  533. -- Please attach any files you think might be helpful to the author.
  534. -- Especially OBUL.CTL, possibly AUTOEXEC.BAT, CONFIG.SYS, etc.
  535. -------------------------------------------------------------------
  536.  
  537.  
  538.  
  539. 5  Revision History
  540.    ----------------
  541.  
  542. 001    - released 01-APR-91
  543.     - this was the initial release
  544.     - supports Opus 1.14 (maybe earlier releases)
  545.     - supports Opus 1.20 if LASTUS##.DAT has not changed
  546.  
  547. 002    - released 06-APR-91
  548.         - added problem report form
  549.     - fixed nasty bug where OBUL.PRM was being improperly I/O'ed
  550.       ("r", not "rb" etc.) and causing spontaneous failures of
  551.       '-g' and '-d' options
  552.     - mentioned that OACOMP generates warnings with OECC labels
  553.         - thanks go to Furlan Primus
  554.  
  555. 003    - release 20-APR-91
  556.     - "wb" fix for 002 killed my BULLETS.OEC file where both a
  557.       cr & nl were not being written.  Sigh!
  558.  
  559.  
  560. 6  Future Enhancements
  561.    -------------------
  562.  
  563. menu system for editting, maintanence, compiling, viewing of bulletins
  564. pull task number from Opus
  565. generate .BBS file directly without using external compiler
  566. automatic columns will use the screen width in LASTUS##.DAT file.
  567. support OEC tokens in OBUL definitions: [user],[date],[time],etc.
  568.  
  569.  
  570. 7  Credits
  571.    -------
  572.  
  573. 7.1  Contacting The Author
  574.      ---------------------
  575.  
  576. To contact the author of OBUL, try one of these:
  577. MODEM:       Micro Magic CBCS @ 205/830-2362  3-12-2400/8N1
  578. FIDONET:     sysop of 1:373/12
  579. USENET:      sysop@umagic.fidonet.org
  580.              ...!uunet!ingr!infonode!umagic!sysop
  581. US MAIL:     203 Creek Trail, Madison, AL 35758
  582.  
  583.  
  584. 7.2  Special Thanks
  585.      --------------
  586.  
  587. Carol and Emily for making my life wonderful.
  588. Johm Emmert of Gateway CBCS for helping me get my Opus running.
  589. Scott Williams for helping me with the OBUL name.
  590.  
  591. "I know what it takes to be a man,
  592.  do right by the ones you love,
  593.  always give a helping hand."
  594.             -Tesla-
  595.  
  596. "...and the Trees are all kept equal
  597.  by hatchet, axe, and saw."
  598.              -Rush-
  599.  
  600. 8  Index
  601.    -----
  602. Not yet available.
  603.